home *** CD-ROM | disk | FTP | other *** search
/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / program / 124 / doc / mjc21.doc < prev    next >
Encoding:
Text File  |  1988-10-20  |  10.9 KB  |  227 lines
  1. Distribution Disk - Shareware Atari ST C compiler - version 2.1
  2.  
  3.          copyright 1988 - Mark A. Johnson
  4.                           5315 Holmes Place
  5.                           Boulder, CO 80303
  6.                           GEnie login: MAJOHNSON
  7.  
  8. This disk contains a shareware C compiler for your use and enjoyment,
  9. pass it on to anyone freely as long as it includes this note.
  10.  
  11. I bought my 520ST in April 1986.  Almost all the software I have is either 
  12. public domain or shareware.  I have supported the shareware idea in the past,
  13. but I'd like to see it happen for myself.  If you like what you find here,
  14. please send a donation along with your name and address.  I send out a
  15. newsletter to discuss bugs, enhancements, and hints now and then.  I hope 
  16. you enjoy this software.  It is not for sale by anyone, and I reserve all 
  17. rights to its  ownership.  Feel free to pass it on to other ST owners, 
  18. but please pass on the whole disk, including this "readme" file.  
  19.  
  20. This is the distribution disk for version 2.1 of the compiler.
  21. It contains the basic compiler tools, libraries, source for the libraries, 
  22. source for a number of useful tools, and (hardly any) documentation.
  23.  
  24. The compiler can handle the full language specified in Kernigan & Ritchie's
  25. "The C Programming Language." To save space, the distribution is contained 
  26. in three ARC files:
  27.  
  28.     mjc.arc    - the compiler development environment
  29.     lib.arc    - source code for the libraries
  30.     srcdoc.arc    - source code for a few useful tools and documentation
  31.  
  32. I've also included ARC.TTP to allow you to unpack the disk.  
  33. Here's a description of the files contained in the all the archives:
  34.  
  35. Programs
  36.     cc.ttp    - translates C code to intermediate code
  37.     as.ttp    - translates intermediate code to machine code
  38.     ue.ttp    - public domain microEmacs editor 
  39.     mk.ttp    - simple UN*X style "make" program
  40.     eternal2.prg- a PD ramdisk, survives resets
  41.     ramdisk.dat - data file for ramdisk
  42.     autodisk.prg- Moshe Braner's autoboot floppy copy to ramdisk on boot
  43.  
  44. Libraries and Header Files
  45.     prg.s    - startup intermediate code for .PRG programs
  46.     ttp.s    - startup intermediate code for .TTP programs
  47.     lib.a    - library used to create .TTP programs
  48.     gem.a    - library used to create .PRG programs
  49.     lib.c    - source for most of lib.a
  50.     math.c    - source for the long and floating point math routines
  51.     str.c    - source for the string routines
  52.     fmtio.c    - source for printf, scanf, and all its friends
  53.     gem.c       - source code for gem.a
  54.     stdio.h    - header for the standard i/o routines
  55.     setjmp.h    - header for setjmp/longjmp routines
  56.     gem.h    - header for GEM AES routines
  57.     osbind.h    - header for "standard" GEMTOS bindings
  58.  
  59. Source code
  60.     ss.c    - a simple spreadsheet program
  61.     hd.c        - a hex dump program
  62.     mk.c    - the make program used in the development environment
  63.     lorder.c    - a library checker (makes sure the order is ok)
  64.     bug.c       - tells you what happened in a crash
  65.     
  66. Documentation
  67.     as.doc    - documentation on the intermediate code
  68.     readme.doc    - this file
  69.     eternal2.doc- describes ramdisks in general and eternal2 in particular
  70.     autodisk.doc- describes what autodisk.prg does and how to use it
  71.  
  72. I have a 520ST with one single-sided floppy, so this disk is really a
  73. collection of many disks I use.  Let's get started by making an autobooting
  74. development environment disk.  Copy MJC.ARC and ARC.TTP to a fresh floppy
  75. and extract all the files out of MJC.ARC (see ARC.DOC).  Then do the 
  76. following (in order):
  77.  
  78.     create an AUTO folder
  79.     copy ETERNAL2.PRG into AUTO
  80.         copy AUTODISK.PRG into AUTO
  81.         copy RAMDISK.DAT into AUTO
  82.         the following files should be in the root directory
  83.         UE.TTP
  84.         CC.TTP
  85.         AS.TTP
  86.         MK.TTP
  87.         TTP.S
  88.         LIB.A
  89.         DESKTOP.INFO
  90.  
  91. Now, whenever you boot the system with this disk, it will prompt you for the
  92. date (it's important to tell it the truth, MK.TTP uses file timestamps
  93. to tell whether or not to build something), copy all the files to the
  94. ramdisk, and then puts you back on the desktop.
  95.  
  96. The compiler (CC.TTP) is preprocessor, parser, and code generator all rolled
  97. into a single program.  Please refer to the "C Programming Language" by K&R.
  98. The compiler has the following features beyond K&R:
  99.  
  100.     - symbol names can be any length
  101.     - built-in 6800 trap generator "trap(NUM, arg1, arg2, ...)"
  102.     - structure assignments
  103.     - register variables
  104.     - "assembler" escapes
  105.     - enum's
  106.  
  107. The floating point is homebrew and new to version 2.0, I am sure it is slow
  108. and buggy.  Be forewarned.  If anyone can improve the floating point code
  109. (see MATH.C in the library source), please let me know so I can 
  110. incorporate it into future releases.
  111.  
  112. The output of the compiler is ascii text and each line maps into a 
  113. single instruction.  This intermediate code is as terse as I can make it (to
  114. save disk space) but is still readable (by me at least).  (I have plans to 
  115. improve this to make things easier for an optimizer).  The output of the 
  116. compiler is always placed in a file called "yc.out" in the current directory.
  117. Any error messages are displayed on the screen.  If "-o filename" is present
  118. on the command line, output will be placed in the specified file instead of
  119. YC.OUT.  The other options to CC.TTP include "-I directory" which gives the
  120. compiler optional directories to search for include files, and "-D name" or
  121. "-D name=value" which lets you #define things on the command line.
  122.  
  123. The assembler (AS.TTP) reads the intermediate code in a single pass and 
  124. keeps everything in memory before generating the file "ya.out" in the 
  125. current directory.  The size limit of the program to be compiled is basically
  126. the size of the available memory.  The "ya.out" file should be renamed to 
  127. one of the standard extensions (.TTP, .PRG, .TOS) before executing it.  
  128. The command line of the assembler should always list a startup file 
  129. first (see ttp.s or prg.s) then the intermediate files of the program, 
  130. then "-L" followed by any libraries.  Any errors encountered by the 
  131. assembler terminates assembly.  A "-m" argument to the assembler will 
  132. include the symbol table (standard Atari format) in the output file.  
  133. A "-o filename" argument will place the output in the specified file instead
  134. of in YA.OUT.  Finally, for those times when the command line is too short
  135. (it's only 128 characters on the ST) a "-f filename" allows AS.TTP to read 
  136. in its list of files to be assembled from a file.
  137.  
  138. A library is simply intermediate code, but is handled differently by the 
  139. assembler than regular intermediate code.  Intermediate code (the 
  140. files before "-L") are read and processed directly; all symbols and
  141. code are accepted without question.  A library is read without processing 
  142. until a symbol is found that is needed but not defined.  From that point 
  143. on, the library is read and processed until the next symbol is encountered.
  144. At the next symbol, the "needed but not defined" test is applied again 
  145. and processing or scanning continues as necessary.
  146.  
  147. The libraries include TOS, VDI, and AES routines taken from the Abacus books.
  148. See lib.doc for some info on the library routines.  I have also included basic
  149. <stdio.h> routines.  I have included the source for LIB.A and GEM.A.  A lot 
  150. of library routines you would expect to see are missing, and for that I 
  151. apologize.  My next major project for the compiler is to port Dale 
  152. Schumaker's DLIB package to MJC.
  153.  
  154. Creating .TTP programs is straightforward and better tested than .PRG (GEM) 
  155. program creation.  In a .TTP process, the main function is called with 
  156. the standard arguments:
  157.  
  158.     main(argc, argv) int argc; char *argv[];
  159.  
  160. Redirection of input and output using >outfile, >>appendfile, or <infile 
  161. on the command line is handled by a startup routine linked into the 
  162. compiled program.  Reads and writes to the screen are built to map '\n' 
  163. to/from "\n\r".
  164.  
  165. Support for GEM programs (.PRG) is not completely debugged.  The GEM.A 
  166. library includes all the VDI and AES functions in the Abacus books,
  167. but has not been extensively tested.  The VDI routines work and 
  168. the window routines, form_alert, and evnt_multi of AES are working.  
  169. My stumbling block right now is adequate documentation 
  170. that would enable me to build a (working) Resource Construction Set.  
  171. I'm (still) working on it...  (Actually, I'm ready to give up on GEM and
  172. roll my own window manager that has forms, menus, and windows, and doesn't
  173. need resource files to work).
  174.  
  175. Let me give you an example of how I use these tools.  I boot with the
  176. disk we made above that sets up my environment with all the tools in
  177. the ramdisk.
  178.  
  179. I then insert a working disk (I only have a single floppy!).
  180. I use microEmacs (UE.TTP) to create or edit C programs.  The MK.TTP program
  181. has built-in rules that enable it to build .TTP or .PRG programs out of
  182. .C source files without any makefile needed.  MK.TTP also will search for
  183. a drive that has a makefile on it, which for me is normally A:.  When I
  184. start up MK.TTP out of the ramdisk, it usually goes over to A: and starts
  185. doing it's thing.  For example, I click on MK.TTP and in the form enter
  186.  
  187.     grep.ttp
  188.  
  189. This will compile the program grep.c and create an executable called grep.ttp.
  190.  
  191. If the C program is contained in a number of files, I normally create a
  192. makefile MK.TTP can use.  Intermediate files are created from the C source
  193. (again a built-in rule in MK.TTP) and finally the object is linked together
  194. by an entry in the makefile.  For example, say I have a spreadsheet program
  195. composed of four files: main.c, io.c, calc.c, and display.c.  The following
  196. makefile would do the trick:
  197.  
  198. # makefile for a (mythical) spreadsheet program
  199.  
  200. OBJ = main.s io.s calc.s display.s
  201.  
  202. ss.ttp: $(OBJ)
  203.   d:as.ttp d:ttp.s $(OBJ) -L d:lib.a
  204.     
  205. io.c main.c display.c: stdio.h
  206.  
  207.  
  208. With the above, I can build the spreadsheet after editing by simply double 
  209. clicking and letting it go.  When you don't tell MK.TTP what to build, it
  210. will build the first object it finds, which in the above example is SS.TTP.
  211.  
  212. Only those files that need to be compiled will be compiled.  When everything
  213. is compiled then the objects will be linked together to form the executable.
  214. The source for MK.TTP is included SRC.ARC, so take a look in there for more 
  215. information on how it works.  It has lots of functions built-in which you
  216. may find useful.  
  217.  
  218. If you insist on doing things by hand, then double click CC.TTP and give it
  219. an argument like "file.c".  This will compile FILE.C into intermediate code, 
  220. which is found in YC.OUT in the current directory.  You can then double
  221. click AS.TTP and give it "d:ttp.s yc.out -L d:lib.a" to assemble and link 
  222. the startup file TTP.S, the compiler output YC.OUT and the library LIB.A.  
  223. For GEM programs, you can replace TTP.S with PRG.S and add GEM.A after the -L.
  224.  
  225. To build libraries or tools, use the compiler.  There are makefiles included
  226. with the source code for them.  Write me if you have problems with any of this!
  227.